docs: migrate to DocumenterVitepress + docstring audit#355
Open
ocots wants to merge 1 commit into
Open
Conversation
- docs/Project.toml: add DocumenterVitepress, LiveServer - docs/make.jl: switch to MarkdownVitepress format, new nav, bases.txt guard - docs/api_reference.jl: refactor to CTBase pattern (modules_config loop, unified Internals page, subdirectory="api") - .github/workflows/Documentation.yml: restrict to stable version tags - docs/src/.vitepress/config.mts: inject nav array + CT remote CSS/JS assets - docs/src/getting-started.md: new guide (install, mental model, walkthrough) - docs/src/index.md: fix module overview table - docs/src/model/index.md: fix layer table + add text fence language - docs/src/model/components.md: fix broken OCP/Validation/ reference - docs/src/model/types_and_traits.md: fix broken philosophy link - docs/src/serialization/index.md: rename to Extensions, add text fence Docstring audit (qualify all julia-repl examples, standardize sections): - Building/state.jl, control.jl, variable.jl, times.jl, objective.jl - Building/dynamics.jl: replace non-standard sections, clean up examples - Building/time_dependence.jl: fix backslash escape, standardize sections - Building/constraints.jl, build.jl: fix wrong API signatures in examples - Building/name_validation.jl: qualify private function examples - Solutions/build_solution.jl, solution_types.jl: qualify time_grid examples - ext/CTModelsJLD.jl, CTModelsJSON.jl: qualify export/import examples
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates the CTModels.jl documentation to DocumenterVitepress, following the pattern established in CTBase.jl. Also includes a full docstring audit of all public symbols.
Documentation infrastructure
docs/Project.toml: addDocumenterVitepress,LiveServerdocs/make.jl: switch toMarkdownVitepressformat; new navigation structure;deploydocsguarded bybases.txtdocs/api_reference.jl: refactor to CTBase pattern —modules_configloop for public pages, one unified Internals page,subdirectory="api".github/workflows/Documentation.yml: restrict deployment trigger to stable version tags (v[0-9]+\.[0-9]+\.[0-9]+)docs/src/.vitepress/config.mts: inject explicit nav array + remote CT CSS/JS assets (generated byDocumenterVitepress.generate_template)Guides
docs/src/getting-started.md: new entry-point guide (installation, mental model, 5-minute walkthrough for OCP building, solution assembly, initial guess)docs/src/index.md: fix module overview table (was referencing non-existentCTModels.OCP)docs/src/model/index.md: fix layer table + addtextlanguage to ASCII pipeline diagramdocs/src/model/components.md: fix broken reference to non-existentOCP/Validation/pathdocs/src/model/types_and_traits.md: replace broken local philosophy link with Handbook referencedocs/src/serialization/index.md: rename page to "Extensions"; addtextlanguage to dispatch diagramDocstring audit
Root cause fixed throughout: all
julia-replexamples used unqualified calls (PreModel(),state!(), etc.) that would fail at the REPL since CTModels has no top-level exports. All examples now useCTModels.*qualified calls.Additional fixes per file:
Building/dynamics.jl# Preconditions/# Behaviorsections with# Returns/# Throws; remove examples with wrong API signaturesBuilding/time_dependence.jl\dotescape →\\dot; standardize sectionsBuilding/constraints.jl__constraint!example (wrong typeDict()→ConstraintsDictType(), mismatchedlb/ubdimensions)Building/build.jltimes!, non-in-placedynamics!) with correct qualified workflowBuilding/objective.jlBuilding/times.jlvariable!prerequisite to free-time examplesSolutions/build_solution.jltime_gridexamples; remove non-standard# BehaviorsectionSolutions/solution_types.jlMultipleTimeGridModelconstructor example; remove non-standard# Behaviorsectionext/CTModelsJLD.jlexport_ocp_solution/import_ocp_solutionexamplesext/CTModelsJSON.jl